\input macros
\drafttrue
\tolerance=2500
\def\bookline{\CLOS\  Specification}
\def\chapline{Programmer Interface Concepts}

\beginChapter 1.{Common Lisp Object System Specification}%
{Programmer Interface Concepts}{Programmer Interface Concepts}

Authors: Daniel G. Bobrow, Linda G. DeMichiel, Richard P.
Gabriel,\hfil\break Sonya E. Keene, Gregor Kiczales, and David A.
Moon.

Draft Dated: Feb 8, 1988\hfil\break
Limited Distribution and Not for Publication\hfil\break
All Rights Reserved

The authors wish to thank Patrick Dussud, Kenneth Kahn,
Jim Kempf,\hfil\break Larry Masinter, Mark Stefik,
Daniel L. Weinreb, and Jon L White\hfil\break
for their contributions to this document.

\endTitlePage

\beginSection{Introduction}

The \CLOS\ is an object-oriented extension to Common Lisp
based on generic functions, multiple inheritance, declarative
method combination, and a meta-object protocol.

The first two chapters of this specification present a description of
the standard Programmer Interface for the \CLOS.  The first chapter
contains a description of the concepts of the \CLOS, and the second
contains a description of the functions and macros in the \CLOS\
Programmer Interface.  The chapter ``The \CLOS\ Meta-Object
Protocol'' describes how the \CLOS\ can be customized to support
other existing object-oriented paradigms and to define new ones.

The fundamental objects of the \CLOS\ are classes, instances,
generic functions, and methods. 

A {\bit class\/} object determines the structure and behavior of a set
of other objects, which are called its {\bit instances}. 
Every Common Lisp object is an {\bit
instance\/} of a class.  The class of an object determines the set of
operations that can be performed on the object.

A {\bit generic function\/} is a function whose behavior depends on the
classes or identities of the arguments supplied to it.  A generic
function object contains a set of methods, a lambda-list, a
method combination type, and other information.  The {\bit methods} define
the class-specific behavior and operations of the generic function; a
method is said to {\bit specialize\/} a generic function.  When invoked,
a generic function executes a subset of its methods based on the
classes of its arguments.

A generic function can be used in 
the same ways that an ordinary function can be used in Common Lisp; in
particular, a generic function can be used as an argument to {\bf
funcall} and {\bf apply} and can be given a global or a local name.

A {\bit method\/} is an object that contains a method function, a sequence of
{\bit parameter specializers\/} that specify when the given method is
applicable, and a sequence of {\bit qualifiers\/} that is used by the
{\bit method combination\/} facility to distinguish among methods.  Each
required formal parameter of each method has an associated parameter
specializer, and the method will be invoked only on arguments that
satisfy its parameter specializers.

The method combination facility controls the selection of methods, the
order in which they are run, and the values that are returned by the
generic function.  The \CLOS\ offers a default method combination type
and provides a facility for declaring new types of method combination.

\endSection%{Introduction}

\beginSection{Error Terminology}

The terminology used in this document to describe erroneous
situations differs from the terminology used in {\it Common Lisp:
The Language}, by Guy L. Steele Jr.  This terminology involves {\bit
situations}; a situation is the evaluation of an expression in some
specific context. For example, a situation might be the invocation of
a function on arguments that fail to satisfy some specified
constraints.

In the specification of the \CLOS, the behavior of programs in all situations
is described, and the options available to the implementor are defined. No
implementation is allowed to extend the syntax or semantics of the \OS\ except
as explicitly defined in the \OS\ specification. In particular, no
implementation is allowed to extend the syntax of the \OS\ in such a way that
ambiguity between the specified syntax of \OS\ and those extensions is
possible.

``When situation $S$ occurs, an error is signaled.''

This terminology has the following meaning:

\beginlist

\item{\bull} If this situation occurs, an error will be signaled in
the interpreter and in code compiled under all compiler safety
optimization levels.

\item{\bull} Valid programs may rely on the fact that an error will be
signaled in the interpreter and in code compiled under all compiler
safety optimization levels.

\item{\bull} Every implementation is required to detect such an error
in the interpreter and in code compiled under all compiler safety
optimization levels.

\endlist

``When situation $S$ occurs, an error should be signaled.''

This terminology has the following meaning:

\beginlist

\item{\bull} If this situation occurs, an error will be signaled at
least in the interpreter and in code compiled under the safest
compiler safety optimization level.

\item{\bull} Valid programs may not rely on the fact that an error will be
signaled.

\item{\bull} Every implementation is required to detect such an error
at least in the interpreter and in code compiled under the safest
compiler safety optimization level.

\item{\bull} When an error is not signaled, the results are undefined (see
below).

\endlist

``When situation $S$ occurs, the results are undefined.''

This terminology has the following meaning:

\beginlist

\item{\bull} If this situation occurs, the results are unpredictable.  The
results may range from harmless to fatal to the running system.

\item{\bull} No valid program should cause this situation to happen.

\item{\bull} Implementations are allowed to detect this situation and
signal an error, but no implementation is required to detect the
situation.

\item{\bull} No implementation is allowed to extend the semantics of the
\OS\ to this situation; the effects of the situation may be harmless, but
they must remain undefined.

\endlist

``The \CLOS\ may be extended to cover situation $S$\negthinspace.''

The meaning of this terminology is that an implementation is free to treat
situation $S$ in one of three ways:

\beginlist

\item{\bull} When situation $S$ occurs, an error is signaled at least
in the interpreter and in code compiled under the safest compiler
safety optimization level.

\item{\bull} When situation $S$ occurs, the results are undefined.

\item{\bull} When situation $S$ occurs, the results are defined and
specified.

\endlist

In addition, this terminology has the following meaning:

\beginlist

\item{\bull} No portable program can depend on the effects of this
situation, and all portable programs are required to treat the situation
as undefined.

\endlist

``Implementations are free to extend the syntax $S$\negthinspace.''

This terminology has the following meaning:

\beginlist

\item{\bull} Implementations are allowed to define unambiguous extensions
to syntax $S$\negthinspace.

\endlist

The \CLOS\ specification may disallow certain extensions while allowing others.

\endSection%{Error Terminology}

\beginSection{Classes}

A {\bit class\/} is an object that determines the structure and behavior 
of a set of other objects, which are called its {\bit instances}.   

A class can inherit structure and behavior from other classes.  
A class whose definition refers to other classes for the purpose of
inheriting from them is said to be a {\bit subclass\/} of each of
those classes.  The classes that are designated for purposes of
inheritance are said to be {\bit superclasses\/}
of the inheriting class.

A class can have a {\bit name}. The function {\bf class-name} takes a
class object and returns its name. The name of an anonymous class is
{\bf nil}.  A symbol can {\bit name\/} a class.  The function {\bf
symbol-class} takes a symbol and returns the class that the symbol
names. A class has a {\bit proper name\/} if the name is a symbol
and if the name of the class
names that class.  That is, a class~$C$ has the {\bit proper
name\/}~$S$ if $S=$ {\tt (class-name $C$)} and $C=$ {\tt (symbol-class
$S$)}.  Notice that it is possible for {\tt (symbol-class $S\sub 1$)}
$=$ {\tt (symbol-class $S\sub 2$)} and $S\sub 1\neq S\sub 2$.

A class $C\sub{1}$ is a {\bit direct superclass\/} of a class
$C\sub{2}$ if $C\sub{2}$ explicitly designates $C\sub{1}$ as a
superclass in its definition.  In this case $C\sub{2}$ is a {\bit
direct subclass\/} of $C\sub{1}$.  A class $C\sub{n}$ is a {\bit
superclass\/} of a class $C\sub{1}$ if there exists a series of
classes $C\sub{2},\ldots,C\sub{n-1}$ such that $C\sub{i+1}$ is a
direct superclass of $C\sub{i}$ for $1 \leq i<n$.  In this case, 
$C\sub{1}$ is a {\bit subclass\/} of $C\sub{n}$.  A class is
considered neither a superclass nor a subclass of itself.  That is, if
$C\sub{1}$ is a superclass of $C\sub{2}$, then $C\sub{1} \neq
C\sub{2}$.  The set of classes consisting of some given
class $C$ along with all of its superclasses is called ``$C$ and its
superclasses.''

Each class has a {\bit class precedence list}, which is a total ordering
on the set of the given class and its superclasses.  The total ordering
is expressed as a list ordered from most specific to least specific.
The class precedence list is used in several ways.  In general, more
specific classes can {\bit shadow}, or override, features that would
otherwise be inherited from less specific classes.  The method selection
and combination process uses the class precedence list to order methods
from most specific to least specific. 
 
When a class is defined, the order in which its direct superclasses
are mentioned in the defining form is important.  Each class has a
{\bit local precedence order\/}, which is a list consisting of the
class followed by its direct superclasses in the order mentioned
in the defining form.

A class precedence list is always consistent with the local precedence
order of each class in the list.  The classes in each local precedence
order appear within the class precedence list in the same order.  If
the local precedence orders are inconsistent with each other, no class
precedence list can be constructed, and an error is signaled.
The class precedence list and its computation is discussed
in the section ``Determining the Class Precedence List.''

Classes are organized into a {\bit directed acyclic graph}.  There are
two distinguished classes, named {\bf t} and {\bf standard-object}.
The class named {\bf t} has no superclasses.  It is a superclass of
every class except itself.  The class named {\bf standard-object} is
an instance of the class {\bf standard-class} and is a superclass of
every class that is an instance of {\bf standard-class} except itself.

\vfill\eject
There is a mapping from the Common Lisp Object System class space into
the Common Lisp type space.  Many of the standard Common Lisp types
specified in {\it Common Lisp: The Language\/} have a corresponding
class that has the same name as the type.  Some Common Lisp types do
not have a corresponding class.  The integration of the type and class
systems is discussed in the section ``Integrating Types and Classes.''

Classes are represented by objects that are themselves
instances of classes.  The class of the class of an object is termed
the {\bit metaclass\/} of that object.  When no misinterpretation is
possible, the term {\bit metaclass\/} will be used to refer to a class
that has instances that are themselves classes.  The metaclass
determines the form of inheritance used by the classes that are its
instances and the representation of the instances of those classes.
The \CLOS\ provides a default metaclass, {\bf standard-class}, that is
appropriate for most programs.  The meta-object protocol provides
mechanisms for defining and using new metaclasses.

Except where otherwise specified, all classes mentioned in this
chapter are instances of the class {\bf standard-class}, all generic
functions are instances of the class {\bf standard-generic-function},
and methods are instances of the class {\bf standard-method}.

\beginsubSection{Defining Classes}

The macro {\bf defclass} is used to define a new class.  The syntax for 
{\bf defclass} is given in Figure~2-1.   

The definition of a class includes:

\beginlist

\item{\bull} The name of the new class. For newly defined classes
this name is a proper name.

\item{\bull} The list of the direct superclasses of the new class. 

\item{\bull} A set of {\bit slot specifiers}.  Each slot specifier
includes the name of the slot and zero or more {\bit slot options}.  A
slot option pertains only to a single slot. If a class definition
contains two slot specifiers with the same name, an error is signaled.

\item{\bull} A set of {\bit class options}.  Each class option pertains 
to the class as a whole.  
\endlist

The slot options and class options of the {\bf defclass} form provide
mechanisms for the following:

\beginlist

\item{\bull} Supplying a default initial value form for a given slot.  

\item{\bull} Requesting that methods for generic functions
be automatically generated for reading or writing slots. 

\item{\bull} Controlling whether one copy of a given slot is shared by
instances of the class or whether each instance of the class has its
own copy of that slot.

\item{\bull} Supplying a set of initialization arguments and initialization
argument defaults to be used in instance creation.

%\item{\bull} Requesting that a constructor function be automatically
%generated for making instances of the new class.

\item{\bull} Indicating that the metaclass should be other than the default.

\endlist 

\endsubSection%{Defining Classes}

\goodbreak

\beginsubSection{Creating Instances of Classes}

The generic function {\bf make-instance} creates and returns a new
instance of a class.  The \OS\ provides several mechanisms for
specifying how a new instance is to be initialized.  For example, it
is possible to specify the initial values for slots in newly created
instances either by giving arguments to {\bf make-instance} or by
providing default initial values.  Further initialization activities
can be performed by methods written for generic functions that are
part of the initialization protocol.  The complete initialization
protocol is described in the section ``Object Creation and
Initialization.''

\endsubSection%{Creating Instances of Classes}

\beginsubSection{Slots}

An object that has {\bf standard-class} as its metaclass has zero or
more named slots.  The slots of an object are determined by the class
of the object.  Each slot can hold one value.  The name of a slot is a
symbol that can be used as a Common Lisp variable name.

When a slot does not have a value, the slot is said to be {\bit
unbound}.  When an unbound slot is read, the generic
function {\bf slot-unbound} is invoked. The system-supplied primary method
for {\bf slot-unbound} signals an error.

A {\bit local slot\/} is defined to be a slot that is visible to exactly
one instance, namely the one in which the slot is allocated.  A {\bit
shared slot\/} is defined to be a slot that is visible to more than one
instance of a given class and its subclasses.

A class is said to {\bit define\/} a slot with a given name when
the {\bf defclass} form for that class contains a slot specifier with
that name.  Defining a local slot does not immediately create a slot;
it causes a slot to be created each time an instance of the class is
created.  Defining a shared slot immediately creates a slot.

The {\bf :allocation} slot option to {\bf defclass} controls the kind
of slot that is defined.  If the value of the {\bf :allocation} slot
option is {\bf :instance}, a local slot is created.  If the value of
{\bf :allocation} is {\bf :class}, a shared slot is created.

A slot is said to be {\bit accessible\/} in an instance of a class if
the slot is defined by the class of the instance or is inherited from
a superclass of that class.  At most one slot of a given name can be
accessible in an instance.  A detailed explanation of the inheritance
of slots is given in the section ``Inheritance of Slots and Slot
Options.''

The default initial value form for a slot is defined by the \hbox{{\bf
:initform}} slot option. When the {\bf :initform} form is used to
supply a value, it is evaluated in the lexical environment in which
the {\bf defclass} form was evaluated. The {\bf :initform} along with
the lexical environment in which the {\bf defclass} form was evaluated
is called a {\bit captured\/} {\bf :initform}.

\endsubSection%{Slots}

\vfill\eject 

\beginsubSection{Accessing Slots}

Slots can be accessed in two ways: by use of the primitive function
{\bf slot-value} and by use of generic functions generated by the {\bf
defclass} form.

The function {\bf slot-value} can be used with any of the slot names
specified in the {\bf defclass} form to access a specific slot in an
instance of the given class.  

The macro {\bf defclass} provides syntax for generating methods to
read and write slots.  If a {\bit reader\/} is requested, a method is
automatically generated for reading the value of the slot, but no
method for storing a value into it is generated.  If a {\bit writer\/}
is requested, a method is automatically generated for storing a value
into the slot, but no method for reading its value is generated.  If
an {\bit accessor\/} is requested, a method for reading the value of
the slot and a method for storing a value into the slot are
automatically generated.  Reader and writer methods are implemented
using {\bf slot-value}.

When a reader or writer is specified for a slot, the name of the
generic function to which the generated method belongs is directly
specified.  If the name specified for the writer option is the symbol
{\it name}, the name of the generic function for writing the slot
is the symbol {\it name}, and the generic function takes two
arguments: the new value and the instance, in that order.  If the name
specified for the accessor option is the symbol {\it name}, the
name of the generic function for reading the slot is the symbol {\it
name\/}, and the name of the generic function for writing the slot is
the list {\tt (setf {\it name\/})}.

A generic function created or modified by supplying reader, writer, or
accessor slot options can be treated exactly as an ordinary generic
function.

Note that {\bf slot-value} can be used to read or write the value of a
slot whether or not reader or writer methods exist for that slot.
When {\bf slot-value} is used, no reader or writer methods are
invoked.

The macro {\bf with-slots} can be used to establish a lexical
environment in which specified slots are lexically available as if they
were variables.  The macro {\bf with-slots} invokes the function {\bf
slot-value} to access the specified slots.

The macro {\bf with-accessors} can be used to establish a lexical
environment in which specified slots are lexically available through
their accessors as if they were variables.  The macro {\bf
with-accessors} invokes the appropriate accessors to access the
specified slots.

\endsubSection%{Accessing Slots}
\endSection%{Classes}

\beginSection{Inheritance}

A class can inherit methods, slots, and some {\bf defclass} options
from its superclasses.  
 
\beginsubSection{Inheritance of Methods}

A subclass inherits methods in the sense that any method applicable to
all instances of a class is also applicable to all instances of any
subclass of that class.

The inheritance of methods acts the same way regardless of whether the
method was created by using one of the method-defining forms or by
using one of the {\bf defclass} options that causes methods to be
generated automatically.

The inheritance of methods is described in detail in the section
``Method Selection and Combination.''   

\endsubSection%{Inheritance of Methods}

\beginsubSection{Inheritance of Slots and Slot Options}

The set of the names of all slots accessible in an instance of a class
$C$ is the union of the sets of names of slots defined by $C$ and its
superclasses. 

In the simplest case, only one class among $C$ and its superclasses
defines a slot with a given slot name.  If a slot is defined by a
superclass of $C$\negthinspace, the slot is said to be {\bit
inherited}.  The characteristics of the slot are determined by the
slot specifier of the defining class.  Consider the defining class for
a slot $S$\negthinspace.  If the value of the {\bf :allocation} slot
option is {\bf :instance}, then $S$ is a local slot and each instance
of $C$ has its own slot named $S$ that stores its own value.  If the
value of the {\bf :allocation} slot option is {\bf :class}, then $S$
is a shared slot, the class that defined $S$ stores the value, and all
instances of $C$ can access that single slot.  If the {\bf
:allocation} slot option is omitted, {\bf :instance} is used.

In general, more than one class among $C$ and its superclasses can
define a slot with a given name.  In such cases, only one slot with
the given name is accessible in an instance of $C$\negthinspace, and
the characteristics of that slot are a combination of the several slot
specifiers, computed as follows:

\beginlist

\item{\bull} All the slot specifiers for a given slot name are ordered
from most specific to least specific, according to the order in $C$'s class
precedence list of the classes that define them.

\item{\bull} The allocation of a slot is controlled by the most specific
slot specifier.  If the most specific slot specifier does not contain an
{\bf :allocation} slot option, {\bf :instance} is used.  Less specific
slot specifiers do not affect the allocation.

\item{\bull} The default initial value form for a
slot is the value of the {\bf :initform} slot option in the most
specific slot specifier that contains one.  If no slot specifier
contains an {\bf :initform} slot option, the slot has no default
initial value form.

\item{\bull} The contents of a slot will always be of type {\tt
(and} $T\sub 1$ $\ldots$ $T\sub n${\tt )} where $T\sub 1 \ldots T\sub n$ are
the values of the {\bf :type} slot options contained in all of the slot
specifiers.  If no slot specifier contains the {\bf :type} slot option, the
contents of a slot will always be of type {\bf t}. The result
of attempting to store in a slot
a value that does not satisfy the type of the slot is undefined.

\item{\bull} The set of initialization arguments that initialize a given
slot is the union of the initialization arguments declared in the {\bf
:initarg} slot options in all the slot specifiers.

\endlist

A consequence of the allocation rule is that a shared slot can be
shadowed.  For example, if a class $C\sub 1$ defines a slot named $S$
whose value for the {\bf :allocation} slot option is {\bf :class},
that slot is accessible in instances of $C\sub 1$ and all of its
subclasses.  However, if $C\sub 2$ is a subclass of $C\sub 1$ and also
defines a slot named $S$\negthinspace, $C\sub 1$'s slot is not shared
by instances of $C\sub 2$ and its subclasses. When a class
$C\sub 1$ defines a shared slot, any subclass $C\sub 2$ of $C\sub
1$ will share this single slot unless the {\bf defclass} form for
$C\sub 2$ specifies a slot of the same name or there is a superclass
of $C\sub 2$ that precedes $C\sub 1$ in the class precedence list of
$C\sub 2$ that defines a slot of the same name.

A consequence of the type rule is that the value of a slot satisfies
the type constraint of each slot specifier that contributes to that
slot.  Because the result of attempting to store in a slot a value
that does not satisfy the type constraint for the slot is undefined,
the value in a slot might fail to satisfy its type constraint.

The {\bf :reader}, {\bf :writer}, and {\bf :accessor} slot options
create methods rather than define the characteristics of a slot.
Reader and writer  methods are inherited in the sense described in
the section ``Inheritance of Methods.''

Methods that access slots use only the name of the slot and the type
of the slot's value.  Suppose a superclass provides a method that
expects to access a shared slot of a given name, and a subclass defines
a local slot with the same name.  If the method provided by the
superclass is used on an instance of the subclass, the method accesses
the local slot.

\beginsubSection{Inheritance of Class Options}

The {\bf :default-initargs} class option is inherited.  The set of
defaulted initialization arguments for a class is the union of the
sets of initialization arguments specified in the {\bf
:default-initargs} class options of the class and its superclasses.
When more than one default initial value form is supplied for a given
initialization argument, the default initial value form that is used
is the one supplied by the class that is most specific according to
the class precedence list.

If a given {\bf :default-initargs} class option specifies an
initialization argument of the same name more than once, an
error is signaled.

\endsubSection%{Inheritance of Class Options}

\vfill\eject
\beginsubSection{Examples}

\screen!

(defclass C1 () 
    ((S1 :initform 5.4 :type number) 
     (S2 :allocation :class)))

(defclass C2 (C1) 
    ((S1 :initform 5 :type integer)
     (S2 :allocation :instance)
     (S3 :accessor C2-S3)))
\endscreen!

Instances of the class {\tt C1} have a local slot named {\tt S1}, whose default
initial value is 5.4 and whose value should always be a number.
The class {\tt C1} also has a shared slot named {\tt S2}.

There is a local slot named {\tt S1} in instances of {\tt C2}.  The
default initial value of {\tt S1} is 5.  The value of {\tt S1} will be
of type {\tt (and integer number)}.  There are also local slots named
{\tt S2} and {\tt S3} in instances of {\tt C2}.  The class {\tt C2}
has a method for {\tt C2-S3} for reading the value of slot {\tt S3};
there is also a method for {\tt setf} of {\tt C2-S3} that writes the
value of {\tt S3}.

\endsubSection%{Examples of Inheritance}
\endSection%{Inheritance}

\beginSection{Redefining Classes}  

A class that is an instance of {\bf standard-class} can be redefined
if the new class will also be an instance of {\bf standard-class}.
Redefining a class modifies the existing class object to reflect the
new class definition; it does not create a new class object for the
class.  Any method object created by a {\bf :reader}, {\bf :writer}, or
{\bf :accessor} option specified by the old {\bf defclass} form is
removed from the corresponding generic function, unless that same
method is specified by the new {\bf defclass} form.

% any function specified by the {\bf :constructor}
% option of the old {\bf defclass} form is removed from the
% corresponding symbol function cell.

When the class $C$ is redefined, changes are propagated to its instances
and to instances of any of its subclasses.  Updating such an
instance occurs at an implementation-dependent time, but no later than
the next time a slot of that instance is read or written.  Updating an
instance does not change its identity as defined by the {\bf eq}
function.  The updating process may change the slots of that
particular instance, but it does not create a new instance.  Whether
updating an instance always consumes storage is implementation dependent.

Note that redefining a class may cause slots to be added or deleted.
If a class is redefined in such a way that the set of local
slots accessible in an instance is the same and the order of slots
in storage is unchanged, no instances are updated.

The value of a slot specified as shared both in the new class and
in the old class is moved from the shared slot of the old
class into the shared slot of the new class.  If such a shared slot was
unbound in the old class, it will be unbound in the new class.
Newly added shared slots are initialized.

Each newly added shared slot is set to the result of evaluating the
captured {\bf :initform} form for the slot that was specified in the
{\bf defclass} form for the new class. If there is no {\bf :initform}
form, the slot is unbound.

If a class is redefined in such a way that the set of local slots
accessible in an instance of the class is changed, a two-step process
of updating the instances of the class takes place.  This two-step
process can happen in other circumstances in some implementations.
For example, in some implementations this two-step process will be
triggered if the order of slots in storage is changed.

The first step modifies the structure of the instance by adding new
local slots and discarding local slots that are not defined in the new
version of the class.
The second step initializes the newly added local slots and performs
any other user-defined actions.

\beginsubSection{Modifying the Structure of Instances}

The first step modifies the structure of instances of the redefined
class to conform to its new class definition.  Local slots specified
by the new class definition that are not specified by the old class
are added, and local slots not specified by the new class definition
that are specified by the old class are discarded.

The values of local slots specified by both the new and old classes
are retained. If such a local slot was unbound, it remains unbound.

The value of a slot specified as local in the new class and shared in
the old class is moved from the shared slot of the old class into the
local slot of the instance.  If such a shared slot was unbound, the local
slot will be unbound.

\endsubSection%{Modifying the Structure of the Instance}

\beginsubSection{Initializing Newly added Local Slots}

The second step initializes the newly added local slots and performs
any other user-defined actions.  This step is implemented by a generic
function {\bf update-instance-structure}, which is called after
completion of the first step of modifying the structure of the
instance.

The generic function {\bf update-instance-structure} takes four
arguments: the instance being updated after it has undergone the first
step, a list of the names of slots that were added, a list of the
names of slots that were discarded, and a property list containing the
slot names and values of slots that were discarded and had values.
Included among the discarded slots are slots that were local in the
old class and that are shared in the new class.

There is a system-supplied primary method for {\bf
update-instance-structure} whose parameter specializer for its
instance argument is the class {\bf standard-object}. This method
initializes the newly added slots.

Any local slot of the new version of the class that does not
have the same name as a slot of the old version of the class is
initialized as follows:

\beginlist

\item{\bull} If the new version of the class specifies or inherits
an {\bf :initform} form for the slot, the value of the slot is set to
the result of evaluating the captured {\bf :initform} form.

\item{\bull} If no {\bf :initform} form is specified or inherited,
the slot remains unbound.

\endlist

This initialization behavior is the same as the initialization
behavior of {\bf make-instance} except that no initialization methods
are invoked and no {\bf make-instance} initialization arguments are
used.

\endsubSection%{Initializing Newly added Local Slots}

Methods for {\bf update-instance-structure} can be defined to specify
actions to be taken when an instance is updated.  If only {\bf :after}
methods for {\bf update-instance-structure} are defined, they will be
run after the system-supplied primary method for initialization and
therefore will not interfere with the default behavior of {\bf
update-instance-structure}.

\beginsubSection{Extensions}

There are two allowed extensions to class redefinition: 

\beginlist

\item{\bull} The \OS\ may be extended to permit the new class
to be an instance of a metaclass other than the metaclass of the
old class.

\item{\bull} The \OS\ may be extended to support an updating process
when either the old or the new class is an instance of a
class other than {\bf standard-class} that is not a built-in class.

\endlist

\endsubSection%{Extensions}

\endSection%{Redefining Classes}

\beginSection{Changing the Class of an Instance}

The function {\bf change-class} can be used to change the class of an
instance from its current class, $C\sub {\hbox{{\prmseven from}}}$, to a
different class, $C\sub {\hbox{{\prmseven to}}}$; it changes the
structure of the instance to conform to the definition of the class
$C\sub {\hbox{{\prmseven to}}}$.

Note that changing the class of an instance may cause slots to be
added or deleted. 

When {\bf change-class} is invoked on an instance, a two-step process
of updating the instances of the class takes place.  
The first step modifies the structure of the instance by 
adding new local slots and discarding local slots that are not
specified in the new version of the instance.  The second step
initializes the newly added local slots and performs any other
user-defined actions.

\beginsubSection{Modifying the Structure of the Instance}

In order to make the instance conform to the class $C\sub
{\hbox{{\prmseven to}}}$, local slots specified by the class $C\sub
{\hbox{{\prmseven to}}}$ that are not specified by the class $C\sub
{\hbox{{\prmseven from}}}$ are added, and local slots not specified by
the class $C\sub {\hbox{{\prmseven to}}}$ that are specified by the
class $C\sub {\hbox{{\prmseven from}}}$ are discarded.

The values of local slots specified by both the class $C\sub
{\hbox{{\prmseven to}}}$ and the class $C\sub {\hbox{{\prmseven
from}}}$ are retained. If such a local slot was unbound, it remains
unbound.

The values of slots specified as shared in the class $C\sub
{\hbox{{\prmseven from}}}$ and as local in the class $C\sub
{\hbox{{\prmseven to}}}$ are retained.

This first step of the update does not affect the values of any shared
slots.

\endsubSection%{Modifying the Structure of the Instance}

\beginsubSection{Initializing Newly added Local Slots}

The second step of the update initializes the newly added slots and
performs any other user-defined actions.  This step is implemented by
the generic function {\bf class-changed}.  The generic function {\bf
class-changed} is invoked by {\bf change-class} after 
the first step of the update has been completed.

The generic function {\bf class-changed} is invoked on two arguments
computed by {\bf change-class}.  The first argument passed is a copy
of the instance being updated and is an instance of the class $C\sub
{\hbox{{\prmseven from}}}$; this copy has dynamic extent within the
generic function {\bf change-class}.  The second argument is the
instance as updated so far by {\bf change-class} and is an instance of
the class $C\sub {\hbox{{\prmseven to}}}$.

There is a system-supplied primary method for {\bf class-changed} that
has two parameter specializers, each of which is the class {\bf
standard-object}. This method initializes the newly added slots.  A
local slot of the class $C\sub {\hbox{{\prmseven to}}}$ with no slot
by the same name in the class $C\sub {\hbox{{\prmseven from}}}$ is
initialized as follows:

\beginlist

\item{\bull} If the class $C\sub {\hbox{{\prmseven to}}}$ specifies
or inherits an {\bf :initform} form for the slot, the value of the
slot is set to the result of evaluating the captured {\bf
:initform}.

\item{\bull} If no {\bf :initform} form is specified or inherited,
the slot remains unbound.

\endlist

This initialization behavior is the same as the initialization
behavior of {\bf make-instance} except that no initialization methods
are invoked and no {\bf make-instance} initialization arguments are
used.

\endsubSection%{Initializing Newly added Local Slots}

Methods for {\bf class-changed} can be defined to specify actions to
be taken when an instance is updated.  If only {\bf :after} methods
for {\bf class-changed} are defined, they will be run after the
system-supplied primary method for initialization and therefore will
not interfere with the default behavior of {\bf class-changed}.

\endSection%{Changing the Classes of an Instance}

\beginSection{Integrating Types and Classes} 

The \CLOS\ maps the space of classes into the Common Lisp type space.
Every class that has a proper name has a corresponding type with the same 
name.  

The proper name of every class is a valid type specifier.  In
addition, every class object is a valid type specifier.  Thus the
expression {\tt (typep {\it object class\/})} evaluates to true if the
class of {\it object\/} is {\it class\/} itself or a subclass of {\it
class}.  The evaluation of the expression {\tt (subtypep {\it class1
class2\/})} returns the values {\bf t~t} if {\it class1\/} is a
subclass of {\it class2\/} or if they are the same class; otherwise it
returns the values {\bf nil~t}.  If $I$ is an instance of some class
$C$ named $S$ and $C$ is an instance of {\bf standard-class}, the
evaluation of the expression {\tt (type-of $I$\/)} will return $S$ if
$S$ is the proper name of $C$\negthinspace; if $S$ is not the proper
name of $C$\negthinspace, the expression {\tt (type-of $I$\/)} will
return $C$\negthinspace.

Because class names and class objects are type specifiers, they can
be used in the special form {\bf the} and in type declarations.

Many but not all of the predefined Common Lisp type specifiers have a
corresponding class with the same proper name as the type.  These type
specifiers are listed in Figure~1-1.  For example, the type {\bf array}
has a corresponding class named {\bf array}.  No type specifier that is a
list, such as {\tt (vector double-float 100)}, has a corresponding class.
The form {\bf deftype} does not create any classes.

Each class that corresponds to a predefined Common Lisp type specifier
can be implemented in one of three ways, at the discretion of each
implementation.  It can be a {\bit standard class\/} (of the kind
defined by {\bf defclass}), a {\bit structure class\/} (defined
by {\bf defstruct}), or a {\bit built-in class\/} (implemented in
a special, non-extensible way).

A built-in class is one whose instances have restricted capabilities or
special representations.  Attempting to use {\bf defclass} to define 
subclasses of a built-in class signals an error.  Calling {\bf
make-instance} to create an instance of a built-in class signals an error.
Calling {\bf slot-value} on an instance of a built-in class signals an
error.  Redefining a built-in class or using {\bf change-class} to change
the class of an instance to or from a built-in class signals an error.
However, built-in classes can be used as parameter specializers in
methods.

%The \OS\ specifies that all predefined Common Lisp type specifiers
%listed in Figure~1-1 are built-in classes, but a particular
%implementation is allowed to extend the \OS\ to define some of them as
%standard classes or as structure classes.

It is possible to determine whether a class is a built-in class by
checking the metaclass.  A standard class is an instance of {\bf
standard-class}, a built-in class is an instance of {\bf
built-in-class}, and a structure class is an instance of {\bf
structure-class}.

Each structure type created by {\bf defstruct} without using the {\bf
:type} option has a corresponding class.  This class is an instance of
{\bf structure-class}.  
%A portable program must assume that {\bf
%structure-class} is a subclass of {\bf built-in-class} and has the
%same restrictions as built-in classes.  Whether {\bf structure-class}
%in fact is a subclass of {\bf built-in-class} is
%implementation dependent. 
The {\bf :include} option of {\bf defstruct} creates a direct
subclass of the class that corresponds to the included structure.
Calling {\bf
make-instance} to create an instance of {\bf structure-class}
signals an error.

The purpose of specifying that many of the standard Common Lisp type
specifiers have a corresponding class is to enable users to write methods that
discriminate on these types.  
Method selection requires that a class precedence list can be
determined for each class. 

The hierarchical relationships among the Common Lisp type specifiers
are mirrored by relationships among the classes corresponding to those
types.  The existing type hierarchy is used for determining the
class precedence list for each class that corresponds to a predefined
Common Lisp type.  In some cases, {\it Common Lisp: The Language\/}
does not specify a local precedence order for two supertypes of a
given type specifier.  For example, {\bf null} is a subtype of both
{\bf symbol} and {\bf list}, but {\it Common Lisp: The Language\/}
does not specify whether {\bf symbol} is more specific or less
specific than {\bf list}.  The \CLOS\ specification defines those
relationships for all such classes.

The following figure lists the set of classes required by the \OS\ that
correspond to predefined Common Lisp type specifiers.  The superclasses of
each such class are presented in order from most specific to most general,
thereby defining the class precedence list for the class. The local precedence
order for each type specifier can be derived from this table.

\boxfig
{\dimen0=.75pc
\tabskip \dimen0 plus .5 fil
\halign to \hsize {#\hfil\tabskip \dimen0 plus 1fil&#\hfil\tabskip \dimen0 plus .5 fil&&#\hfil\cr  %was &&#
\noalign{\vskip -9pt}
\hfil\bf  Predefined Common Lisp Type&\bf Class Precedence List\span\omit\span\omit\cr
\noalign{\vskip 2pt\hrule\vskip 2pt}
array&(array t)\cr
bit-vector&(bit-vector vector array sequence t)\cr
character&(character t)\cr
complex&(complex number t)\cr
cons&(cons list sequence t)\cr
float&(float number t)\cr
integer&(integer rational number t)\cr
list&(list sequence t)\cr
null&(null symbol list sequence t)\cr
number&(number t)\cr
ratio&(ratio rational number t)\cr
rational&(rational number t)\cr
sequence&(sequence t)\cr
string&(string vector array sequence t)\cr
symbol&(symbol t)\cr
t&(t)\cr
vector&(vector array sequence t)\cr
\noalign{\vskip -9pt}
}}
\caption{}
\endfig

Individual implementations can be extended to define other type
specifiers to have a corresponding class.  Individual implementations
can be extended to add other subclass relationships and to add other
elements to the class precedence lists in the above table, as long as
they do not violate the type relationships and disjointness
requirements specified by {\it Common Lisp: The Language\/}.
A standard class defined with no direct superclasses is guaranteed to
be disjoint from all of the classes in the table, except for the
class named {\bf t}.

\vfill\eject

The following Common Lisp types will have corresponding classes when
Common Lisp is modified to define them each as being disjoint from {\bf
cons}, {\bf symbol}, {\bf array}, {\bf number}, and {\bf character}:

{\bf function}\hfil\break
{\bf hash-table}\hfil\break
{\bf package}\hfil\break
{\bf pathname}\hfil\break
{\bf random-state}\hfil\break
{\bf readtable}\hfil\break
{\bf stream}

\endSection%{Integrating Types and Classes}

\beginSection{Determining the Class Precedence List}

The {\bf defclass} form for a class provides a total ordering on that
class and its direct superclasses.  This ordering is called the {\bit
local precedence order}.  It is an ordered list of the class and its
direct superclasses. The {\bit class precedence list\/} for a
class $C$ is a total ordering on $C$ and its superclasses that is consistent
with the local precedence orders for each of $C$ and its superclasses.

A class precedes its direct superclasses, and a
direct superclass precedes all other direct superclasses specified to
its right in the superclasses list of the {\bf defclass} form.  For
every class $C$, define $$R\sub C=\{(C,C\sub 1),(C\sub 1,C\sub
2),\ldots,(C\sub {n-1},C\sub n)\}$$ where $C\sub 1,\ldots,C\sub n$ are
the direct superclasses of $C$ in the order in which
they are mentioned in the {\bf defclass} form. These ordered pairs
generate the total ordering on the class $C$ and its direct
superclasses.

Let $S\sub C$ be the set of $C$ and its superclasses. Let $R$ be
$$R=\bigcup\sub{c\in {S\sub C}}R\sub c$$

The set $R$ may or may not generate a partial ordering, depending on
whether the $R\sub c$, $c\in S\sub C$, are consistent; it is assumed
that they are consistent and that $R$ generates a partial ordering.
When the $R\sub c$ are not consistent, it is said that $R$ is inconsistent.

%This partial ordering is generated by taking the the transitive
%closure of the set $R\cup \{(c,c) \vert c\in {S\sub C}\}$.  When
%$(C\sub 1,C\sub 2)\in R$\negthinspace, it is said that $C\sub 1$ 
%{\bit precedes or equals} $C\sub 2$.  Intuitively, $C\sub 1$ precedes
%or equals $C\sub 2$ when $C\sub 1=C\sub 2$ or $C\sub 2$ is a
%superclass of $C\sub 1$.  
%
%Recall that a partial ordering of the set $S$ is a relation between 
%objects of $S$ that is transitive, reflexive, and antisymmetric. The 
%set $\{(c,c) \vert c\in {S\subC}\}$ was added to the transitive 
%closure of the set $R$ in order to make the relation reflexive.  In 
%the remainder of this section the set of precedence relations $R$ and 
%not the partial ordering will be used.

To compute the class precedence list for~$C$\negthinspace,
topologically sort the elements of $S\sub C$ with respect to the
partial ordering generated by $R$\negthinspace.  When the topological
sort must select a class from a set of two or more classes, none of
which are preceded by other classes with respect to~$R$\negthinspace,
the class selected is chosen deterministically, as described below.

If $R$ is inconsistent, an error is signaled.


\goodbreak

\beginsubSection{Topological Sorting}

Topological sorting proceeds by finding a class $C$ in~$S\sub C$ such
that no other class precedes that element according to the elements
in~$R$\negthinspace.  The class $C$ is placed first in the result.
Remove $C$ from $S\sub C$, and remove all pairs of the form $(C,D)$,
$D\in S\sub C$, from $R$\negthinspace. Repeat the process, adding
classes with no predecessors to the end of the result.  Stop when no
element can be found that has no predecessor.

If $S\sub C$ is not empty and the process has stopped, the set $R$ is
inconsistent. If every class in the finite set of classes is preceded
by another, then $R$ contains a loop. That is, there is a chain of
classes $C\sub 1,\ldots,C\sub n$ such that $C\sub i$ precedes
$C\sub{i+1}$, $1\leq i<n$, and $C\sub n$ precedes $C\sub 1$.

Sometimes there are several classes from $S\sub C$ with no
predecessors.  In this case select the one that has a direct
subclass rightmost in the class precedence list computed so far.
Because a direct superclass precedes all other direct superclasses to
its right, there can be only one such candidate class. If there is no
such candidate class, $R$ does not generate a partial ordering---the
$R\sub c$, $c\in S\sub C$, are inconsistent.

In more precise terms, let $\{N\sub 1,\ldots,N\sub m\}$, $m\geq 2$, be
the classes from $S\sub C$ with no predecessors.  Let $(C\sub
1\ldots C\sub n)$, $n\geq 1$, be the class precedence list
constructed so far.  $C\sub 1$ is the most specific class, and $C\sub
n$ is the least specific.  Let $1\leq j\leq n$ be the largest number
such that there exists an $i$ where $1\leq i\leq m$ and $N\sub i$
is a direct superclass of $C\sub j$; $N\sub i$ is placed next.

The effect of this rule for selecting from a set of classes with no
predecessors is that the classes in a simple superclass chain are
adjacent in the class precedence list and that classes in each
relatively separated subgraph are adjacent in the class
precedence list. For example, let $T\sub 1$ and $T\sub 2$ be subgraphs
whose only element in common is the class $J$\negthinspace. Suppose
that no superclass of $J$ appears in either $T\sub 1$ or $T\sub 2$.
Let $C\sub 1$ be the bottom of $T\sub 1$; and let $C\sub 2$ be the
bottom of $T\sub 2$.  Suppose $C$ is a class whose direct superclasses
are $C\sub 1$ and $C\sub 2$ in that order, then the class precedence
list for $C$ will start with $C$ and will be followed by all classes
in $T\sub 1$ except $J$. All the classes of $T\sub 2$ will be next.
The class $J$ and its superclasses will appear last.

\endsubSection%{Topological Sorting}

\beginsubSection{Examples}

This example determines a class precedence list for the
class {\tt pie}.  The following classes are defined:

\screen!

(defclass pie (apple cinnamon) ())

(defclass apple (fruit) ())

(defclass cinnamon (spice) ())

(defclass fruit (food) ())

(defclass spice (food) ())

(defclass food () ())
\endscreen!

The set $S$~$=$ $\{${\tt pie, apple, cinnamon, fruit, spice, food, t}$\}$. The
set $R$~$=$ $\{${\tt (pie, apple),
(apple, cinnamon), (apple, fruit), (cinnamon, spice),
(fruit, food), (spice, food),\break
(food, t)}$\}$.

The class {\tt pie} is not preceded by anything, so it comes first;
the result so far is {\tt (pie)}.  Remove {\tt pie} from $S$ and
pairs mentioning {\tt pie} from $R$ to get $S$~$=$ $\{${\tt
apple, cinnamon, fruit, spice, food, t}$\}$ and $R$~$=$~$\{${\tt
(apple, cinnamon), (apple, fruit), (cinnamon, spice),
(fruit, food), (spice, food), (food, t)}$\}$.

\vfill\eject
The class {\tt apple} is not preceded by anything, so it is next; the
result is {\tt (pie apple)}. Removing {\tt apple} and the relevant
pairs results in $S$~$=$ $\{${\tt cinnamon, fruit, spice, food, t}$\}$ and
$R$~$=$ $\{${\tt (cinnamon, spice), (fruit, food),
(spice, food), (food, t)}$\}$.

The classes {\tt cinnamon} and {\tt fruit} are not preceded by
anything, so the one with a direct subclass rightmost in the class
precedence list computed so far goes next.  The class {\tt apple} is a
direct subclass of {\tt fruit}, and the class {\tt pie} is a direct
subclass of {\tt cinnamon}.  Because {\tt apple} appears to the right of
{\tt pie} in the precedence list, {\tt fruit} goes next, and the
result so far is {\tt (pie apple fruit)}.  $S$~$=$ $\{${\tt cinnamon,
spice, food, t}$\}$; $R$~$=$ $\{${\tt (cinnamon, spice), (spice,
food), (food, t)}$\}$.

The class {\tt cinnamon} is next, giving the result so far as {\tt
(pie apple fruit cinnamon)}.  At this point $S$~$=$ $\{${\tt spice,
food, t}$\}$; $R$~$=$ $\{${\tt (spice, food), (food, t)}$\}$.

The classes {\tt spice}, {\tt food}, and {\tt t} are added in that
order, and the class precedence list is {\tt (pie apple fruit cinnamon
spice food t)}.

It is possible to write a set of class definitions that cannot be 
ordered.   For example: 

\screen!

(defclass new-class (fruit apple) ())

(defclass apple (fruit) ())
\endscreen!

The class {\tt fruit} must precede {\tt apple} because the local
ordering of superclasses must be preserved.  The class {\tt apple} must
precede {\tt fruit} because a class always precedes its own
superclasses.  When this situation occurs, an error is signaled when
the system tries to compute the class precedence list.

Note the following example, which might appear to be a
conflicting set of definitions: 

\screen!

(defclass pie (apple cinnamon) ())

(defclass pastry (cinnamon apple) ())

(defclass apple () ())

(defclass cinnamon () ())
\endscreen!

The class precedence list for {\tt pie} is  {\tt (pie apple cinnamon t)}.

The class precedence list for {\tt pastry} is  {\tt (pastry cinnamon apple t)}.

It is not a problem for {\tt apple} to precede {\tt cinnamon} in the
ordering of the superclasses of {\tt pie} but not in the ordering for
{\tt pastry}.  However, it is not possible to build a new class that
has both {\tt pie} and {\tt pastry} as superclasses.

\endsubSection%{Examples}

\endSection%{Determining the Class Precedence List}


\beginSection{Generic Functions and Methods}

\beginsubSection{Introduction to Generic Functions}

A generic function object contains a set of methods, a
lambda-list, a method combination type, and other information.

Like an ordinary Lisp function, a generic function takes arguments,
performs a series of operations, and perhaps returns useful values.
An ordinary function has a single body of code that is always executed
when the function is called.  A generic function has a set of bodies
of code of which a subset is selected for execution. The selected
bodies of code and the manner of their combination are determined by
the classes or identities of one or more of the arguments to the
generic function and by its method combination type.

Ordinary functions and generic functions are called with identical
syntax.
 
Generic functions are true functions that can be passed as arguments and
used as the first argument to {\bf funcall} and {\bf apply}.

In Common Lisp, a name can be given to an ordinary function in one of
two ways: a {\bit global\/} name can be given to a function using the
{\bf defun} construct; a {\bit local\/} name can be given using the
{\bf flet} or {\bf labels} special forms.  A generic function can be
given a global name using the {\bf defmethod} or {\bf defgeneric}
construct.  A generic function can be given a local name using the
{\bf generic-flet}, {\bf generic-labels}, or {\bf with-added-methods}
special forms.  The name of a generic function, like the name of an
ordinary function, can be either a symbol or a two-element list whose
first element is {\bf setf} and whose second element is a symbol.
This is true for both local and global names.

The {\bf generic-flet} special form creates new local generic
functions using the set of methods specified by the method definitions
in the {\bf generic-flet} form.  The scoping of generic function names
within a {\bf generic-flet} form is the same as for {\bf flet}.

The {\bf generic-labels} special form creates a set of new mutually
recursive local generic functions using the set of methods specified
by the method definitions in the {\bf generic-labels} form.  The
scoping of generic function names within a {\bf generic-labels} form
is the same as for {\bf labels}.

The {\bf with-added-methods} special form creates new local generic
functions by adding the set of methods specified by the method
definitions with a given name in the {\bf with-added-methods} form to
copies of the methods of the lexically visible generic function of the
same name. If there is a lexically visible ordinary function of the
same name as one of specified generic functions, that function
becomes the method function of the default method for the new generic
function of that name.

The {\bf generic-function} special form creates an anonymous generic
function with the set of methods specified by the method definitions
in the {\bf generic-function} form.

\vfill\eject

When a {\bf defgeneric} form is evaluated, one of three actions
is taken:

\beginlist

\item{\bull} If a generic function of the given name already exists,
the existing generic function object is modified.  Methods specified
by the current {\bf defgeneric} form are added, and any methods in the
existing generic function that were defined by a previous {\bf
defgeneric} form are removed.  No other methods in the generic
function are affected or replaced.

\item{\bull} If the given name names a non-generic function, a
macro, or a special form, an error is signaled.

\item{\bull} Otherwise a generic function is created with the
methods specified by the method definitions in the {\bf defgeneric}
form.

\endlist

Some forms specify the options of a generic function,
such as the type of method combination it uses or its argument
precedence order.  These forms will be referred to as ``forms that
specify generic function options.'' These forms are: {\bf defgeneric},
{\bf generic-function}, {\bf generic-flet}, {\bf generic-labels}, and
{\bf with-added-methods}.

Some forms define methods for a generic function.  These forms will be
referred to as ``method-defining forms.'' These forms are: {\bf
defgeneric}, {\bf defmethod}, {\bf generic-function}, {\bf
generic-flet}, {\bf generic-labels}, {\bf with-added-methods}, and
{\bf defclass}. Note that all the method-defining forms except {\bf
defclass} and {\bf defmethod} can specify generic function options and
so are also forms that specify generic function options.

\endsubSection%{Introduction to Generic Functions}

\beginsubSection{Introduction to Methods}

A method object contains a method function, a sequence of {\bit
parameter specializers\/} that specify when the given method is
applicable, a lambda-list, and a sequence of {\bit qualifiers\/} that
are used by the method combination facility to distinguish among
methods.

A method object is not a function and cannot be invoked as a function.  An
implementation may extend the \OS\ so that method objects are functions.
Various mechanisms in the \OS\ take a method object and invoke its method
function, as is the case when a generic function is invoked.  When this
occurs it is said that the method is invoked or called.

A method-defining form contains the code that is to be run when the
arguments to the generic function cause the method that it defines to
be invoked.  When a method-defining form is evaluated, a method object
is created and one of four actions is taken:

\beginlist

\item{\bull} If a generic function of the given name already exists
and if a method object already exists that agrees with the new one on
parameter specializers and qualifiers, the new method object replaces
the old one.  For a definition of one method agreeing with another on
parameter specializers and qualifiers, see the section 
``Agreement on Parameter Specializers and Qualifiers.''

\item{\bull} If a generic function of the given name already exists
and if there is no method object with the same parameter specializers
and qualifiers, the existing generic function object is modified to
contain the new method object.

\vfill\eject

\item{\bull} If the given name names a non-generic function, a macro,
or a special form, an error is signaled.

\item{\bull} Otherwise a generic function is created with the methods
specified by the method-defining form.

\endlist

If the lambda-list of a new method is not congruent with the lambda-list
of the generic function, an error is signaled.  If a
method-defining form that cannot specify generic function options
creates a new generic function, a lambda-list for that generic
function is derived from the lambda-lists of the methods in the
method-defining form in such a way as to be congruent with them.  For
a discussion of {\bit congruence}, see the section ``Congruent
Lambda-lists for All Methods of a Generic Function.''

Each method has a {\bit specialized lambda-list}, which determines
when that method can be applied.  A specialized lambda-list is like
an ordinary lambda-list except that a {\bit specialized parameter\/}
may occur instead of the name of a required parameter.  A specialized parameter
is a list {\tt ({\it variable-name parameter-specializer-name\/})},
where {\it parameter-specializer-name\/} is one of the following: 

\beginlist

\item{\bull} The name of any class

\item{\bull} {\tt ({\bf eql} {\it form\/})}

\endlist

A parameter specializer name denotes a parameter specializer as follows:

\beginlist

\item{\bull} The name of a class denotes the class object.

\item{\bull} The list {\tt ({\bf eql} {\it form\/})} denotes {\tt
({\bf eql} {\it object\/})}, where {\it object\/} is the result of
evaluating {\it form\/}.  The form {\it form\/} is evaluated in the
lexical environment in which the method-defining form was
evaluated.  Note that {\it form\/} is evaluated only once, at the time
the method is defined, not each time the generic function is called.
\endlist

Parameter specializer names are used in macros intended as the
user-level interface ({\bf defmethod}), while parameter specializers
are used in the functional interface.

Only required parameters may be specialized, and there must be a
parameter specializer for each required parameter.  For notational
simplicity, if some required parameter in a specialized lambda-list in
a method-defining form is simply a variable name, its parameter
specializer defaults to the class named {\bf t}.

Given a generic function and a set of arguments, an {\bit applicable
method\/} is a method for that generic function whose parameter
specializers are satisfied by their corresponding arguments.  The
following definition specifies what it means for a method to be
applicable and for an argument to satisfy a parameter specializer.

\vfill\eject

Let $\langle A\sub 1, \ldots, A\sub n\rangle$ be the required
arguments to a generic function in order. Let $\langle P\sub 1,
\ldots, P\sub n\rangle$ be the parameter specializers corresponding to
the required parameters of the method $M$ in order.  The method $M$ is
{\bit applicable\/} when each $A\sub i$ {\bit satisfies\/} $P\sub i$.
If $P\sub i$ is a class, and if $A\sub i$ is an instance of a class
$C$\negthinspace, then it is said that $A\sub i$ {\bit satisfies\/}
$P\sub i$ when $C=P\sub i$ or when $C$ is a subclass of $P\sub i$.  If
$P\sub i$ is {\tt ({\bf eql} {\it object\/})}, then it is said that
$A\sub i$ satisfies $P\sub i$ when the function {\bf eql} applied to
$A\sub i$ and {\it object} is true.

Because a parameter specializer is a type specifier, the function {\bf
typep} can be used to determine whether an argument satisfies a
parameter specializer during method selection.  Recall that in general a
parameter specializer cannot be a type specifier list, such as {\tt
({\bf vector single-float})}.  The only parameter specializer that can
be a list is {\tt ({\bf eql} {\it object\/})}.  This proposal requires
that Common Lisp be modified to include the type specifier {\bf eql}
to be defined as if the following were evaluated:

$$\hbox{{\tt ({\bf deftype eql} ({\it object\/})
 `({\bf member} {\it ,object\/}))}}$$

A method all of whose parameter specializers are the class named {\bf
t} is called a {\bit default method}; it is always applicable but
may be shadowed by a more specific method.

Methods can have {\bit qualifiers}, which give the method combination
procedure a way to distinguish among methods.  A method that has one
or more qualifiers is called a {\bit qualified\/} method.
A method with no qualifiers is called an {\bit unqualified method}. 
A qualifier is any object other than a list, that is,
any non-{\bf nil} atom.  The qualifiers defined by standard method combination
and by the built-in method combination types are symbols.

In this specification, the terms {\bit primary method\/} and {\bit
auxiliary method\/} are used to partition methods within a method
combination type according to their intended use.  In standard method
combination, primary methods are unqualified methods and auxiliary
methods are methods with a single qualifier that is one of {\bf
:around}, {\bf :before}, or {\bf :after}.  When a method combination
type is defined using the short form of {\bf
define-method-combination}, primary methods are methods qualified with
the name of the type of method combination, and auxiliary methods have
the qualifier {\bf :around}.  Thus the terms {\bit primary method\/}
and {\bit auxiliary method\/} have only a relative definition within a
given method combination type.

\endsubSection%{Introduction to Methods}

\beginsubSection{Agreement on Parameter Specializers and Qualifiers}

Two methods are said to agree with each other on parameter specializers
and qualifiers if the following conditions hold:

\beginlist

\item{1.} Both methods have the same number of required parameters.
Suppose the parameter specializers of the two methods are
$P\sub{1,1}\ldots P\sub{1,n}$ and $P\sub{2,1}\ldots P\sub{2,n}$.

\item{2.} For each $1\leq i\leq n$, $P\sub{1,i}$ agrees with $P\sub{2,i}$.
The parameter specializer $P\sub{1,i}$ agrees with $P\sub{2,i}$ if
$P\sub{1,i}$ and $P\sub{2,i}$ are the same class or if 
$P\sub{1,i}=\hbox{{\tt({\bf eql} $\hbox{{\it object}}\sub 1$)}}$,
$P\sub{2,i}=\hbox{{\tt({\bf eql} $\hbox{{\it object}}\sub 2$)}}$, and
{\tt ({\bf eql} $\hbox{{\it object}}\sub 1$ $\hbox{{\it object}}\sub 2$)}.
Otherwise they do not agree.

\item{3.} The lists of qualifiers of both methods contain the same 
non-{\bf nil} atoms in the same order. That is, the lists are {\bf equal}.

\endlist

\endsubSection%{Agreement on Parameter Specializers and Qualifiers}

\beginsubSection{Congruent Lambda-Lists for All Methods of a Generic Function}

These rules define the congruence of a set of lambda-lists, including the
lambda-list of each method for a given generic function and the
lambda-list specified for the generic function itself, if given.

\beginlist

\item{1.} Each lambda-list must have the same number of required
parameters.

\item{2.} Each lambda-list must have the same number of optional
parameters.  Each method can supply its own default for an optional
parameter.

\item{3.} If any lambda-list mentions {\bf \&rest} or {\bf \&key}, each
lambda-list must mention one or both of them.

\item{4.} If the generic function lambda-list mentions {\bf \&key}, each
method must accept all of the keyword names mentioned after {\bf \&key},
either by accepting them explicitly, by specifying {\bf
\&allow-other-keys}, or by specifying {\bf \&rest} but not {\bf \&key}.
Each method can accept additional keyword arguments of its own.  The
checking of the validity of keyword names is done in the generic
function, not in each method. A method is invoked as if the keyword
argument pair whose  keyword is {\bf :allow-other-keys} and whose value
is {\bf t} were supplied, though no such argument pair will be passed.

\item{5.} The use of {\bf \&allow-other-keys} need not be consistent
across lambda-lists.  If {\bf \&allow-other-keys} is mentioned in 
the lambda-list of any applicable method or of the generic function,
any keyword arguments may be mentioned in the call to the
generic function.

\item{6.} The use of {\bf \&aux} need not be consistent across methods.

If a method-defining form that cannot specify generic function options
creates a generic function, and if the lambda-list for the method
mentions keyword arguments, the lambda-list of the generic function
will mention {\bf \&key} (but no keyword arguments).
\endlist

\endsubSection%{Congruent Lambda-lists for All Methods of a Generic Function}

\beginsubSection{Keyword Arguments in Generic Functions and Methods}

When a generic function or any of its methods mentions {\bf \&key} in
a lambda-list, the specific set of keyword arguments accepted by the
generic function varies according to the applicable methods.  The set
of keyword arguments accepted by the generic function for a particular
call is the union of the keyword arguments accepted by all applicable
methods and the keyword arguments mentioned after {\bf \&key} in the
generic function definition, if any.  A method that has {\bf \&rest}
but not {\bf \&key} does not affect the set of acceptable keyword
arguments.  If the lambda-list of any applicable method or of the
generic function definition contains {\bf \&allow-other-keys}, all
keyword arguments are accepted by the generic function.

Recall that the lambda-list congruence rules require that each method
accept all of the keyword arguments mentioned after {\bf \&key} in the
generic function definition, by accepting them explicitly, by
specifying {\bf \&allow-other-keys}, or by specifying {\bf \&rest} but
not {\bf \&key}.  Each method can accept additional keyword arguments
of its own, in addition to the keyword arguments mentioned in the
generic function definition.

For example, suppose there are two methods defined for {\tt width}
as follows:

\screen!

(defmethod width ((c character-class) &key font) ...)

(defmethod width ((p picture-class) &key pixel-size) ...)
\endscreen!

\noindent Assume that there are no other methods and no generic
function definition for {\tt width}. The evaluation of the
following form will signal an error.

\screen!

(width (make-instance `character-class :char \#\\Q) 
       :font 'baskerville :pixel-size 10)
\endscreen!

The evaluation of the following form will signal an error.

\screen!

(width (make-instance `picture-class :glyph (glyph \#\\Q)) 
       :font 'baskerville :pixel-size 10)
\endscreen!

The evaluation of the following form will not signal an error
if the class named {\tt character-picture-class} is a subclass of
both {\tt picture-class} and {\tt character-class}.

\screen!

(width (make-instance `character-picture-class :char \#\\Q)
       :font 'baskerville :pixel-size 10)
\endscreen!

\endsubSection%{Keyword Arguments in Generic Functions and Methods}

\endSection%{Generic Functions and Methods}

\beginSection{Method Selection and Combination}

When a generic function is called with particular arguments, it must
determine the code to execute.  This code is called the {\bit effective
method\/} for those arguments.  The effective method is a {\bit
combination\/} of the applicable methods in the generic function.  A
combination of methods is a Lisp expression that contains calls to some or
all of the methods.  If a generic function is
called and no methods apply, the generic function {\bf
no-applicable-method} is invoked.

When the effective method has been determined, it is invoked with the same
arguments that were passed to the generic function.  Whatever values it
returns are returned as the values of the generic function.

\beginsubSection{Determining the Effective Method}

The effective method is determined by the following three-step procedure:

\beginlist

\item{1.}{Select the applicable methods.}

\item{2.}{Sort the applicable methods by precedence order, putting
the most specific method first.}

\item{3.}{Apply method combination to the sorted list of
applicable methods, producing the effective method.}

\endlist

\beginsubsubsection{Selecting the Applicable Methods}

This step is described in the section ``Introduction to Methods.''

\endsubsubsection%{Selecting the Applicable Methods}

\beginsubsubsection{Sorting the Applicable Methods by Precedence Order}

To compare the precedence of two methods, their parameter specializers
are examined in order.  The default examination order is from left to
right, but an alternative order may be specified by the {\bf
:argument-precedence-order} option to {\bf defgeneric} or to any of
the other forms that specify generic function options.

The corresponding parameter specializers from each method are
compared.  When a pair of parameter specializers are equal, the next
pair are compared for equality.  If all corresponding parameter
specializers are equal, the two methods must have different
qualifiers; in this case, either method can be selected to precede the
other.

If some corresponding parameter specializers are not equal, the first
pair of parameter specializers that are not equal determines the
precedence.  If both parameter specializers are classes, the more
specific of the two methods is the method whose parameter specializer
appears earlier in the class precedence list of the corresponding
argument.  Because of the way in which the set of applicable methods
is chosen, the parameter specializers are guaranteed to be present in
the class precedence list of the class of the argument.

If just one parameter specializer is {\tt ({\bf eql} {\it
object\/})}, the method with that parameter specializer precedes the
other method.  If both parameter specializers are {\bf eql}
forms, the
specializers must be the same (otherwise the two methods would
not both have been applicable to this argument).

The resulting list of applicable methods has the most specific
method first and the least specific method last.    

\endsubsubsection%{Sorting the Applicable Methods by Precedence Order}

\beginsubsubsection{Applying Method Combination to the Sorted List of Applicable Methods}

In the simple case---if standard method combination is used and all
applicable methods are primary methods---the effective method is the
most specific method.  That method can call the next most specific
method by using the function {\bf call-next-method}.  The method that
{\bf call-next-method} will call is referred to as the {\bit next method}.
The predicate {\bf next-method-p} tests whether a next method exists.

In general, the effective method is some combination of the applicable
methods.  It is defined by a Lisp form that contains calls to some or all
of the applicable methods, returns the value or values that will be
returned as the value or values of the generic function, and optionally
makes some of the methods accessible by means of {\bf call-next-method}.
This Lisp form is the body of the effective method; it is augmented with
an appropriate lambda-list to make it a function.

The role of each method in the effective method is determined by its
method qualifiers and the specificity of the method.  A qualifier
serves to mark a method, and the meaning of a qualifier is
determined by the way that these marks are used by this step
of the procedure.  If an applicable method has an unrecognized
qualifier, this step signals an error and does not include that method
in the effective method.

When standard method combination is used together with qualified methods, 
the effective method is produced as described in the section
``Standard Method Combination.''

Another type of method combination can be specified by using the {\bf
:method-combination} option of {\bf defgeneric} or of any of the other
forms that specify generic function options.  In this way this step of
the procedure can be customized.

New types of method combination can be defined by using the 
{\bf define-method-combination} macro. 

\goodbreak

The meta-object level also offers a mechanism for defining new types
of method combination.  The generic function {\bf
compute-effective-method} receives as arguments the generic function,
the method combination object, and the sorted list of applicable
methods.  It returns the Lisp form that defines the effective method.
A method for {\bf compute-effective-method} can be defined directly by
using {\bf defmethod} or indirectly by using {\bf
define-method-combination}.  A {\bit method combination object} is an
object that encapsulates the method combination type and options
specified by the {\bf :method-combination} option to forms that
specify generic function options.

\endsubsubsection

\beginImplNote
In the simplest implementation, the generic function would compute
the effective method each time it was called.  In practice, this will
be too inefficient for some implementations.  Instead, these
implementations might employ a variety of optimizations of the
three-step procedure. Some illustrative examples of such optimizations
are the following:

\beginlist

\item{\bull} Use a hash table keyed by the class of the arguments to
store the effective method.

\item{\bull} Compile the effective method and save the resulting
compiled function in a table.

\item{\bull} Recognize the Lisp form as an instance of a pattern of
control structure and substitute a closure that implements
that structure.

\item{\bull} Examine the parameter specializers of all methods for the
generic function and enumerate all possible effective methods.
Combine the effective methods, together with code to select from
among them, into a single function and compile that function.  Call
that function whenever the generic function is called.
\endlist
\endImplNote


\endsubSection%{Determining the Effective Method}

\beginsubSection{Standard Method Combination}

Standard method combination is supported by the class {\bf
standard-generic-function}. It is used if no other type of method
combination is specified or if the built-in method combination type
{\bf standard} is specified. 

{\bit Primary methods\/} define the main action of the effective method,  
while {\bit auxiliary methods\/} modify that action in one of three ways.
A primary method has no method qualifiers.

An auxiliary method is a method whose method qualifier is {\bf
:before}, {\bf :after}, or {\bf :around}.  Standard method combination
allows no more than one qualifier per method; if a method definition
specifies more than one qualifier per method, an error is signaled.

\beginlist

\item{\bull}
A {\bf :before} method has the keyword {\bf :before} as its
only qualifier.  A {\bf :before} method specifies code that is to be
run before any primary methods.

\item{\bull}
An {\bf :after} method has the keyword {\bf :after} as its only
qualifier.  An {\bf :after} method specifies code that is to be run
after primary methods.  

\item{\bull}
An {\bf :around} method has the keyword {\bf :around} as its only
qualifier. An {\bf :around} method specifies code that is to
be run instead of other applicable methods but which is
able to cause some of them to be run.

\endlist

The semantics of standard method combination is as follows:

\beginlist

\item{\bull} If there are any {\bf :around} methods, the most specific
{\bf :around} method is called.  It supplies the value or values of the
generic function.

\vfill\eject
\item{\bull} 
Inside the body of an {\bf :around} method, {\bf call-next-method} can
be used to call the next method.  When the next method
returns, the {\bf :around} method can execute more code, perhaps based
on the returned value or values.   An error is signaled if {\bf
call-next-method} is used and there is no applicable method to
call.  The function {\bf next-method-p} may be used to determine whether a
next method exists. 

\item{\bull} 
If an {\bf :around} method invokes {\bf call-next-method}, the next
most specific {\bf :around} method is called, if one is applicable.
If there are no {\bf :around} methods or if {\bf
call-next-method} is called by the least specific {\bf :around}
method, the other methods are called as follows:

\itemitem{--} All the {\bf :before} methods are called, in
most-specific-first order.  Their values are ignored.
An error is signaled if {\bf call-next-method} is used in a
{\bf :before} method.

\itemitem{--} 
The most specific primary method is called.  Inside the body of a
primary method, {\bf call-next-method} may be used to call
the next most specific primary method.  When that method returns,
the previous primary method can execute more code, perhaps based on the
returned value or values.  An error is signaled if {\bf
call-next-method} is used and there are no more applicable primary methods.
The function {\bf next-method-p} may be used to determine whether a
next method exists.  If {\bf call-next-method} is not used, only
the most specific primary method is called.


\itemitem{--} All the {\bf :after} methods are called in
most-specific-last order.  Their values are ignored.
An error is signaled if {\bf call-next-method} is used in an
{\bf :after} method.

\item{\bull} If no {\bf :around} methods were invoked, the most
specific primary method supplies the value or values returned by the
generic function.  The value or values returned by the invocation of
{\bf call-next-method} in the least specific {\bf :around} method are
those returned by the most specific primary method.

\endlist

In standard method combination, if there is an applicable method
but no applicable primary method, an error is signaled.

The {\bf :before} methods are run in most-specific-first order while
the {\bf :after} methods are run in least-specific-first order.  The
design rationale for this difference can be illustrated with an
example.  Suppose class $C \sub 1$ modifies the behavior of its
superclass, $C \sub 2$, by adding {\bf :before} and {\bf :after}
methods. Whether the behavior of the class $C\sub 2$ is defined
directly by methods on $C\sub 2$ or is inherited from its superclasses
does not affect the relative order of invocation of methods on
instances of the class $C\sub 1$.  Class $C \sub 1$'s {\bf :before}
method runs before all of class $C \sub 2$'s methods.  Class $C \sub
1$'s {\bf :after} method runs after all of class $C \sub 2$'s methods.

By contrast, all {\bf :around} methods run before any other methods
run.  Thus a less specific {\bf :around} method runs before a more
specific primary method.

If only primary methods are used and if {\bf call-next-method} is not
used, only the most specific method is invoked; that is, more specific
methods shadow more general ones. 

\endsubSection%{Standard Method Combination}

\vfill\eject
\beginsubSection{Declarative Method Combination}

The macro {\bf define-method-combination} defines new forms of method
combination.  It provides a mechanism for customizing the production
of the effective method; the default procedure for producing an
effective method is described in the section ``Determining the
Effective Method.''  There are two forms of {\bf
define-method-combination}.  The short form is a simple facility while
the long form is more powerful and more verbose.  The long form
resembles {\bf defmacro} in that the body is an expression that
computes a Lisp form; it provides mechanisms for implementing
arbitrary control structures within method combination and for
arbitrary processing of method qualifiers.  The syntax and use of both
forms of {\bf define-method-combination} are explained in Chapter~2.

\endsubSection%{Declarative Method Combination}

\goodbreak

\beginsubSection{Built-in Method Combination Types}

The \CLOS\ provides a set of built-in method combination types.  To
specify that a generic function is to use one of these method
combination types, the name of the method combination type is given as
the argument to the {\bf :method-combination} option to {\bf
defgeneric} or to any of the other forms that specify generic
function options.

The names of the built-in  method combination types are
{\bf +}, {\bf and}, {\bf append}, {\bf list}, {\bf max}, {\bf min}, 
{\bf nconc}, {\bf or}, {\bf progn}, and {\bf standard}.

The semantics of the {\bf standard} built-in method combination type was
described in the section ``Standard Method Combination.''  The other
built-in method combination types are called {\bit simple built-in method
combination types.}

The simple built-in method combination types act as though they were
defined by the short form of {\bf define-method-combination}.  They
recognize two roles for methods:

\beginlist

\item{\bull} An {\bf :around} method has the keyword symbol {\bf
:around} as its sole qualifier.  The meaning of {\bf :around}
methods is the same as in standard method combination.  Use of the
functions {\bf call-next-method} and {\bf next-method-p} is supported
in {\bf :around} methods.

\item{\bull} A primary method has the name of the method combination
type as its sole qualifier.  For example, the built-in method
combination type {\bf and} recognizes methods whose sole qualifier is
{\bf and}; these are primary methods. Use of the functions {\bf
call-next-method} and {\bf next-method-p} is not supported in primary
methods.

\endlist

The semantics of the simple built-in method combination types is as
follows:

\beginlist
\item{\bull}
If there are any {\bf :around} methods, the most specific {\bf :around}
method is called.   It supplies the value or values of the generic function. 

\item{\bull} Inside the body of an {\bf :around} method, the function
{\bf call-next-method} can be used to call the next method.  An error
is signaled if {\bf call-next-method} is used and there is no
applicable method to call.  The function {\bf next-method-p} may be
used to determine whether a next method exists. When the next method
returns, the {\bf :around} method can execute more code, perhaps based
on the returned value or values. 

\item{\bull} If an {\bf :around} method invokes {\bf
call-next-method}, the next most specific {\bf :around} method is
called, if one is applicable.  If there are no {\bf :around} methods
or if {\bf call-next-method} is called by the least specific {\bf
:around} method, a Lisp form derived from the name of the built-in
method combination type and from the list of applicable primary
methods is evaluated to produce the value of the generic function.
Suppose the name of the method combination type is {\it operator\/}
and the call to the generic function is of the form

$$(\hbox{{\it generic-function}}\ a\sub 1\ldots a\sub n)$$

\item{} Let $M\sub 1,\ldots,M\sub k$ be the applicable primary methods
in order; then the derived Lisp form is

$$(\hbox{{\it operator}}\ \langle M\sub  1%
\ a\sub 1\ldots a\sub n\rangle\ldots\langle%
M\sub k\ a\sub 1\ldots a\sub n\rangle)$$

\item{} If the expression $\langle M\sub i \ a\sub 1\ldots a\sub
n\rangle$ is
evaluated, the method $M\sub i$ will be applied to the arguments
$a\sub 1\ldots a\sub n$.  If {\it operator\/} is {\bf or},
the expression $\langle M\sub i \ a\sub 1\ldots a\sub n\rangle$ is
evaluated only if $\langle M\sub j \ a\sub 1\ldots a\sub n\rangle$,
$1\leq j<i$, returned {\bf nil}.

\item{} The default order for the primary methods is {\bf
:most-specific-first}.  However, the order can be reversed by supplying
{\bf :most-specific-last} as the second argument to the {\bf
:method-combination} option.  \endlist

\goodbreak

The simple built-in method combination types require exactly one qualifier per
method.  An error is signaled if there are applicable methods with no
qualifiers or with qualifiers that are not supported by the method
combination type. An error is signaled if there are applicable {\bf :around}
methods and no applicable primary methods.

\endsubSection%{Built-in Method Combination Types}

\endSection%{Method Selection and Combination}

\beginSection{Meta-Objects}

The implementation of the \OS\ manipulates classes, methods, and generic
functions.  The meta-object protocol specifies a set of generic
functions defined by methods on classes; the behavior of those generic
functions defines the behavior of the \OS.  The instances of the classes
on which those methods are defined are called {\bit meta-objects}.  Programming
at the meta-object protocol level involves defining new classes of
meta-objects along with methods specialized on these classes.

\beginsubSection{Metaclasses}

The {\bit metaclass\/} of an object is the class of its class.  The
metaclass determines the representation of instances of its instances and
the forms of inheritance used by its instances for slot descriptions and
method inheritance.  The metaclass mechanism can be used to provide
particular forms of optimization or to tailor the \CLOS\ for particular
uses.  The protocol for defining metaclasses is discussed in the chapter
``The \CLOS\ Meta-Object Protocol.''

\endsubSection%{Metaclasses}

\beginsubSection{Standard Metaclasses}

The \CLOS\ provides a number of predefined metaclasses.  These include the
classes {\bf standard-class}, {\bf built-in-class}, and {\bf
structure-class}:

\beginlist

\item{\bull}
The class {\bf standard-class} is the default class of classes defined
by {\bf defclass}.

\item{\bull} The class {\bf built-in-class} is the class whose
instances are classes that have special implementations with
restricted capabilities.  Any class that corresponds to a standard
Common Lisp type specified in {\it Common Lisp: The Language\/}
might be an instance of {\bf built-in-class}.
The predefined Common Lisp type specifiers that are required to have
corresponding classes are listed in Figure~1-1.  It is implementation
dependent whether each of these classes is implemented as a built-in class.

\item{\bull}
All classes defined by means of {\bf defstruct} are instances of 
{\bf structure-class}.
\endlist

\endsubSection%{Standard Metaclasses}

\beginsubSection{Standard Meta-objects}

The \OS\ supplies a set of meta-objects, called {\bit standard
meta-objects}. These include the class {\bf standard-object} and
instances of the classes {\bf standard-method}, {\bf
standard-generic-function}, and {\bf method-combination}.

\beginlist

\item{\bull} 
The class {\bf standard-method} is the default class of
methods defined by the forms {\bf defmethod}, {\bf
defgeneric}, {\bf generic-function}, {\bf generic-flet}, {\bf
generic-labels}, and {\bf with-added-methods}.

\item{\bull}
The class {\bf standard-generic-function} is the default class of 
generic functions defined by the forms {\bf defmethod},
{\bf defgeneric}, {\bf generic-function}, {\bf generic-flet},
{\bf generic-labels}, {\bf with-added-methods}, and {\bf defclass}.

\item{\bull} The class named {\bf standard-object} is an instance of
the class {\bf standard-class} and is a superclass of every class that
is an instance of {\bf standard-class} except itself.

\item{\bull} Every method combination object is an instance of a
subclass of the class {\bf method-combination}.

\endlist

\endsubSection%{Standard Meta-objects} 

\endSection%{Meta-Objects}

\beginSection{Object Creation and Initialization}

The generic function {\bf make-instance} creates and returns a new
instance of a class.  The first argument is a class or the name of a
class, and the remaining arguments form an {\bit initialization argument\/}
list.  

Initialization consists of several distinct steps, including the
following: combining the explicitly supplied initialization arguments
with default values for the unsupplied initialization arguments,
checking the validity of the initialization arguments, allocating
storage for the instance, filling slots with values, and executing
user-supplied methods that perform additional initialization. 
Each step of {\bf make-instance} is implemented
by a generic function to provide a mechanism for
customizing each step.  In addition, {\bf make-instance} is itself a generic
function and thus also can be customized.

The \OS\ specifies default methods for each step and thus specifies a
well-defined standard behavior for the entire initialization
process.  The standard behavior provides four simple mechanisms for
controlling initialization:

\beginlist

\item{\bull} Declaring a symbol to be an initialization argument for a
slot.  An initialization argument is declared by using the {\bf
:initarg} slot option to {\bf defclass}.  This provides a mechanism
for supplying a value for a slot in a call to {\bf make-instance}.

\item{\bull} Supplying a default initial value form for an
initialization argument.  Default initial value forms for
initialization arguments are defined by using the {\bf
:default-initargs} class option to {\bf defclass}.  A default initial
value form is used if the initialization argument is not explicitly
provided as an argument to {\bf make-instance}.

\item{\bull} Supplying a default initial value form for a slot.  A
default initial value form for a slot is defined by using the {\bf
:initform} slot option to {\bf defclass}.  This default initial value form is
evaluated in the lexical environment of the {\bf defclass} form that
defined it, and the resulting value is stored in the slot, if no
initialization argument associated with that slot is given as an
argument to {\bf make-instance} or is defaulted by {\bf
:default-initargs}.

\item{\bull} Defining methods for {\bf initialize-instance}.  The
slot-filling behavior described above is implemented by a system-supplied
default method for {\bf initialize-instance}.  Additional control over
initialization can be obtained by writing methods for {\bf
initialize-instance}.

\endlist

\beginsubSection{Initialization Arguments}

An initialization argument controls object creation and
initialization.  The {\bf \&rest} argument to {\bf make-instance} is a
list of alternating initialization argument names and values.  It is
often convenient to use keyword symbols to name initialization
arguments, but the name of an initialization argument can be any
symbol, including {\bf nil}.  An initialization argument can be used
in two ways: to fill a slot with a value or to provide an argument for
an initialization method.  A single initialization argument can be
used for both purposes.

An {\bit initialization argument list\/} is a list of alternating
initialization argument names and values.  Its structure is identical
to a property list and also to the portion of an argument list
processed for {\bf \&key} parameters.  As in those lists, if an
initialization argument name appears more than once in an
initialization argument list, the leftmost occurrence supplies the
value and the remaining occurrences are ignored.  The arguments to
{\bf make-instance} (after the first argument) form an initialization
argument list.  Error-checking of initialization argument names is
disabled if the keyword argument pair whose keyword is {\bf
:allow-other-keys} and whose value is non-{\bf nil} appears in the
initialization argument list.

An initialization argument can be associated with a slot.  If the
initialization argument has a value in the initialization argument
list, the value is stored into the slot of the newly created object,
overriding any {\bf :initform} form associated with the slot.  A
single initialization argument can initialize more than one slot.  An
initialization argument that initializes a shared slot stores its
value into the shared slot, replacing any previous value.

An initialization argument can be associated with a method.  Such an
initialization argument is intended as an argument for one or more
methods for {\bf initialize-instance} or {\bf allocate-instance}.
When an object is created, these generic functions are called with the
initialization argument's name and value as a keyword argument pair.
If a value for the initialization argument is not supplied in the
initialization argument list, the method's lambda-list supplies a
default value.

\endsubSection%{Initialization Arguments}


\beginsubSection{Declaring the Validity of Initialization Arguments}

The method for {\bf make-instance} defined for the class {\bf
standard-class} checks the validity of its initialization arguments
and signals an error if an initialization argument is supplied that is
not declared as valid.

Initialization arguments that fill slots are declared as valid by the
{\bf :initarg} slot option to {\bf defclass}.  The {\bf :initarg} slot
option is inherited from superclasses.  Thus the set of valid
initialization arguments that fill slots for a class is the union of
the initialization arguments that fill slots declared as valid by that
class and its superclasses.

Initialization arguments that supply arguments to methods are declared as
valid by defining methods for {\bf initialize-instance} or {\bf
allocate-instance}.  The keyword name of each keyword parameter specifier
in the method's lambda-list becomes an initialization argument for all
classes for which the method is applicable.  Thus method inheritance
controls the set of valid initialization arguments that supply arguments
to methods.

The set of valid initialization arguments for a class is the set of valid
initialization arguments that either fill slots or supply arguments to
methods, along with the predefined initialization argument {\bf
:allow-other-keys}.  The default value for {\bf :allow-other-keys} is
{\bf nil}.  The meaning of {\bf :allow-other-keys} is the same as when it is
passed to an ordinary function.

\endsubSection%{Declaring the Validity of Initialization Arguments}

\vfill\eject

\beginsubSection{Defaulting of Initialization Arguments}

A {\bit default initial value form\/} can be supplied for an initialization
argument by using the {\bf :default-initargs} class option.  If an
initialization argument is declared valid by some particular class,
its default initial value form might be specified by a different class. 
In this case {\bf :default-initargs} is used to supply a default value
for an inherited initialization argument.

The {\bf :default-initargs} option is used only to provide default values
for initialization arguments; it does not declare a symbol as a valid
initialization argument name.

The argument to the {\bf :default-initargs} class option is a list of
alternating initialization argument names and forms.  Each form is the
default initial value form for the corresponding initialization
argument.  The default initial value form of an initialization
argument is used and evaluated only if that initialization argument
does not appear in the arguments to {\bf make-instance} and is not
defaulted by a more specific class.  The default initial value form is
evaluated in the lexical environment of the {\bf defclass} form that
supplied it; the resulting value is used as the initialization
argument's value.

The initialization arguments supplied to {\bf make-instance} are combined
with defaulted initialization arguments to produce a {\bit
defaulted initialization argument list}. A defaulted initialization
argument list is a list of alternating initialization argument names and
values in which unsupplied initialization arguments are defaulted and in
which the explicitly supplied initialization arguments appear earlier in
the list than the defaulted initialization arguments.  Defaulted
initialization arguments are ordered according to the order in the class
precedence list of the classes that supplied the default values.

There is a distinction between the purposes of the {\bf
:default-initargs} and the {\bf :initform} options with respect to the
initialization of slots.  The {\bf :default-initargs} class option
provides a mechanism for the user to give a default initial value form
for an initialization argument without knowing whether the
initialization argument initializes a slot or is passed to a method.
If that initialization argument is not explicitly supplied in a call
to {\bf make-instance}, the default initial value form is used, just
as if it had been supplied in the call.  In contrast, the {\bf
:initform} slot option provides a mechanism for the user to give a
default initial value form for a slot.  An {\bf :initform} form is
used to initialize a slot only if no initialization argument
associated with that slot is given as an argument to {\bf
make-instance} or is defaulted by {\bf :default-initargs}.

The order of evaluation of default value forms and the
order of evaluation of {\bf :initform} forms are
undefined.  If the order of evaluation is important, {\bf
initialize-instance} methods should be used instead.  It is not
recommended that {\bf :initform} forms or default initial value forms
have side effects other than creating new objects.

\endsubSection%{Defaulting of Initialization Arguments}

\vfill\eject
\beginsubSection{Rules for Duplicate Initialization Arguments}

The following rules specify when initialization arguments can be
duplicated:

\beginlist

\item{\bull} The {\bf :initarg} slot option may be specified more than
once for a given slot.

\item{\bull} A single initialization argument can be used to
initialize more than one slot if the same initialization argument name
appears in more than one {\bf :initarg} slot option.

\item{\bull} A single initialization argument can appear 
in the lambda-list of more than one initialization method.

\item{\bull} A given initialization argument name can
appear both in an {\bf :initarg} slot option and in the lambda-list
of an initialization method.

\endlist

The following rules specify what happens when initialization arguments are
duplicated:

\beginlist

\item{\bull} If two or more initialization arguments that initialize
the same slot are given in the arguments to {\bf make-instance}, the
leftmost of these initialization arguments in the initialization
argument list supplies the value, even if the initialization arguments
have different names.

\item{\bull} If two or more different initialization arguments that
initialize the same slot have default values and none is given
explicitly in the arguments to {\bf make-instance}, the initialization
argument that appears in a {\bf :default-initargs} class option in the
most specific of the classes supplies the value. If a single {\bf
:default-initargs} class option specifies two or more initialization
arguments that initialize the same slot and none is given explicitly
in the arguments to {\bf make-instance}, the leftmost in the {\bf
:default-initargs} class option supplies the value, and the values of
the remaining default value forms are ignored.

\item{\bull} Initialization arguments given explicitly in the
arguments to {\bf make-instance} appear to the left of defaulted
initialization arguments. Suppose that the classes $C\sub 1$ and
$C\sub 2$ supply the values of defaulted initialization arguments for
different slots, and suppose that $C\sub 1$ is more specific than
$C\sub 2$; then the defaulted initialization argument whose value is
supplied by $C\sub 1$ is to the left of the defaulted initialization
argument whose value is supplied by $C\sub 2$ in the defaulted
initialization argument list.  If a single {\bf :default-initargs}
class option supplies the values of initialization arguments for two
different slots, the initialization argument whose value is specified
farther to the left in the {\bf default-initargs} class option appears
farther to the left in the defaulted initialization argument list.

\item{\bull} If a slot has both an {\bf :initform} form and an {\bf
:initarg} slot option, and the initialization argument is defaulted
using {\bf :default-initargs} or is supplied to {\bf make-instance},
the captured {\bf :initform} form is neither used nor evaluated.

\endlist

\vfill\eject
The following is an example of the above rules:

\screen!

  (defclass q () ((x :initarg a)))
  (defclass r (q) ((x :initarg b))
    (:default-initargs a 1 b 2))
\endscreen!

$$\vbox{\halign{\strut#\hfil&\quad\hfil#\hfil&\quad\hfil#\hfil\cr
{}&\bf Defaulted&{}\cr
\bf Form&\bf Initialization Argument List&\bf Contents of Slot X\cr
\noalign{\hrule}
{\tt (make-instance 'r)}&{\tt (a 1 b 2)}&{\tt 1}\cr
{\tt (make-instance 'r 'a 3)}&{\tt (a 3 b 2)}&{\tt 3}\cr
{\tt (make-instance 'r 'b 4)}&{\tt (b 4 a 1)}&{\tt 4}\cr
{\tt (make-instance 'r 'a 1 'a 2)}&{\tt (a 1 a 2 b 2)}&{\tt 1}\cr}}$$

\endsubSection%{Rules for Duplication of Initialization arguments}

\beginsubSection{Methods for Initialize-Instance}

The generic function {\bf initialize-instance} uses standard method
combination.  Methods for {\bf initialize-instance} can be defined in
order to perform any initialization that cannot be achieved with the
simple slot-filling mechanisms.

During initialization, {\bf initialize-instance} is invoked
after the following actions have been taken:

\beginlist 

\item{\bull} The defaulted initialization argument list has been computed by
combining the supplied initialization argument list with any default
initialization arguments for the class.

\item{\bull} The validity of the defaulted initialization argument
list has been checked.  If any of the initialization arguments has not
been declared as valid, an error is signaled.

\item{\bull} A new instance whose slots are unbound has been created.

\endlist

The generic function {\bf initialize-instance} is then called with the
new instance and the defaulted initialization argument list.  There is
a system-supplied primary method whose parameter specializer is the
class {\bf standard-object}. This method initializes the slots with
values according to the initialization argument list.  This
method behaves as follows on each slot, whether shared or local:

\beginlist

\item{\bull} If an initialization argument in the defaulted
initialization argument list specifies a value for that slot, that
value is stored into the slot,  even if a value has
already been stored in the slot before the method is run. For example, a
{\bf :before}, an {\bf :around} method, or a more specific primary
method might store a value in the slot, and the system-supplied
primary method will overwrite that value.

\item{\bull} Otherwise if the slot is still unbound and has an {\bf
:initform} form, that form is evaluated in the lexical environment of
its defining {\bf defclass} form and the result is stored into the
slot. For example, if a {\bf :before} method stores a value in the
slot, the {\bf :initform} form will not be used to supply a value for
the slot.

\item{\bull} The rules mentioned in the section ``Rules for Duplicate
Initialization Arguments'' are obeyed.

\endlist

Methods for {\bf initialize-instance} can be defined to specify
actions to be taken when an instance is initialized.  If only {\bf :after}
methods for {\bf initialize-instance} are defined, they will be
run after the system-supplied primary method for initialization and
therefore will not interfere with the default behavior of {\bf
initialize-instance}.

The \OS\ provides two functions that are useful in the bodies of {\bf
initialize-instance} methods.  The function {\bf slot-boundp} returns a
boolean value that indicates whether the slot has a value; this provides
a mechanism for
writing {\bf :after} methods for {\bf initialize-instance} that initialize
slots only if they have not already been initialized.  The function {\bf
slot-makunbound} causes the slot to have no value.

\endsubSection%{Methods for Initialize-Instance }

\beginsubSection{Procedural Definition of Make-Instance}

The generic function {\bf make-instance} behaves as if it were defined as
follows, except that certain optimizations are permitted:

\screen!

(defmethod make-instance ((class standard-class) &rest initargs)
  (setq initargs (default-initargs class initargs))
  (check-initargs class initargs)  
  (let ((instance (apply #'allocate-instance class initargs)))
    (apply #'initialize-instance instance initargs)
    instance))

(defmethod make-instance ((class-name symbol) &rest initargs)
  (apply #'make-instance (symbol-class class-name) initargs))

\endscreen!

This procedure can be customized at either the Programmer Interface level,
the meta-object level, or both.  

Customizing at the Programmer Interface level includes using the {\bf
:initform}, {\bf :initarg}, and {\bf :default-initargs} options to {\bf
defclass}, as well as defining methods for {\bf initialize-instance}.  The
meta-object level supports extra customization by defining methods for
{\bf make-instance}, {\bf default-initargs}, {\bf check-initargs}, and
{\bf allocate-instance}.  Chapters~2 and~3 document each of these generic
functions and the system-supplied primary methods.

Implementations are permitted to make certain optimizations of {\bf
initialize-instance}.  The description of {\bf initialize-instance} in
Chapter~2 mentions the possible optimizations. 

Because of optimization, methods for the generic functions
listed may not be called on every call to {\bf make-instance}
or may not receive exactly the arguments that would be expected.  For
example, {\bf check-initargs} might be called before {\bf
default-initargs} rather than after, if it has already been determined
that the default initialization arguments will be approved by {\bf
check-initargs}.

\endsubSection%{Procedural Definition of MAKE-INSTANCE}
\endSection%{Object Creation and Initialization}

\beginSection{Introduction to Setf Functions}

Setf functions are generalized in the \CLOS\ to setf generic
functions.

A {\bit setf function\/} is called in an expression such as the
following: $$\hbox{{\tt (setf ({\it name . arguments\/}) {\it
new-value\/})}}$$

A setf function can be defined by using a name of the form {\tt
(setf {\it name\/})}.  There is an automatic association between the
setf function named {\tt (setf {\it name\/})} and the function named
{\it name}.

The macro expansion of the {\bf setf} form {\tt (setf ({\it name}
$x\sub 1\ldots x\sub n$) {\it new-value\/})} obeys the following
rules, where the first rule that applies supersedes any later ones:

\beginlist

\item{\bull}If {\it name\/} refers to the global function definition
rather than to a locally defined function or macro and if there is a
{\bf setf} macro defined for {\it name\/} by {\bf defsetf} or {\bf
define-setf-method}, the {\bf setf} macro is used to compute the
expansion.

\item{\bull} If {\it name\/} is defined as a macro in the current
lexical scope, {\bf macroexpand-1} is used to expand \hbox{{\tt ({\it
name} $x\sub 1\ldots x\sub n$)}}, and the resulting expansion is
macro expanded again.

\item{\bull} If {\it name\/} is defined as a special form in the current
lexical scope, an error is signaled.

\item{\bull} The {\bf setf} form is expanded into the equivalent of

\endlist

$$\openup1\jot\vbox{\settabs\+\cr
\+{\tt(}& {\tt let} &{\tt (}& {\tt (}$v\sub 1$&$\ x\sub 1${\tt)}\cr
\+&&&&$\vdots$\cr
\+&&&{\tt(}$v\sub n$&$\ x\sub n${\tt))}\cr
\+&{\tt(funcall} {\tt\#'(setf} {\it name}{\tt)} {\it new-value}\ %
$v\sub 1\ldots v\sub n${\tt))}\cr}$$

Notice that {\bf setf} functions take the new value as the first
argument; therefore, a {\bf setf} generic function can define
methods that discriminate on the new value.

A {\bit function specifier\/} is defined to be either a symbol that
names a function or a list of the form {\tt (setf {\it name\/})}
that names a setf function.

\endSection%{Introduction to Setf Functions}

\endChapter
\bye